Creating and Manipulating Color Set and Color Profile Objects (IM: XO)

Inside Macintosh: QuickDraw GX Objects /: Chapter 4 - Colors and Color-Related Objects / Using Colors and Color-Related Objects

Creating and Manipulating Color Set and Color Profile Objects
This section describes how you can create and interact with color set objects and color profile objects as whole entities--to create, dispose of, copy, compare, clone, load, and unload them. Because color sets and color profiles are QuickDraw GX objects, and you use similar sets of functions to manipulate them, they are considered together in each of the subsequent sections. Manipulating the individual properties of color sets and color profiles is described under "Manipulating Object Properties of Color Sets and Color Profiles" beginning on page 4-46.

Creating and Disposing of a Color Set or Color Profile
QuickDraw GX provides the GXNewColorSet function to allow you to create a new color set. You can also create a new color set that is a copy of an existing color set by calling GXCopyToColorSet.
Once you have created a color set object, you can attach it to a color structure, bitmap structure, or transfer mode structure by putting a reference to it in the color or bitmap
or transfer mode. Colors, bitmaps, and transfer modes also include a specification of
the color space they use; if they use a color set, they must use gxIndexedSpace for their color space.
The following code fragment creates a simple color set (theSet) with two RGB colors: black and white. It assigns the color set to the bitmap structure theBits, which it then assigns to the bitmap shape theBitmap, which it finally assigns to the view device theDevice. The code then disposes of the color set and bitmap shape since those references are no longer needed:
gxSetColor  theColors[2];
gxSetColor  *pColor;
gxColorSet  theSet;
gxBitmap    theBits
gxShape     theBitmap
.
.  /* initialize theBits and theBitmap (not shown) */
.
pColor = &theColors[0];
pColor->rgb.red = pColor->rgb.green = 
                     pColor->rgb.blue = gxColorValue1;
pColor++;
pColor->rgb.red = pColor->rgb.green = pColor->rgb.blue = 0x0000;

theSet = GXNewColorSet(gxRGBSpace, 2, theColors);
theBits.set = theSet;
GXSetBitmap(theBitmap, &theBits, nil);
GXSetViewDeviceBitmap(theDevice, theBitmap);
GXDisposeColorSet(theSet);
GXDisposeShape(theBitmap);
Note
If you use GXNewColorSet to create a color set, and then assign it as a default color set with GXSetDefaultColorSet, be sure to dispose of your reference to that color set immediately after assigning it as the default. That way the new default color set will have the proper owner count of 1, as required by QuickDraw GX.
For color profile objects, QuickDraw GX provides the GXNewColorProfile function (and the GXCopyToColorProfile function) to allow you to create new color profiles. If you have profile information that you want to attach to a color or to a bitmap, you can put that information in object form with GXNewColorProfile and attach it (by reference) to the color or bitmap. For simple drawing, you typically never have to do this, but you might want to create a color profile object in these special instances:

If you want to inhibit color matching for a particular color, you can create a zero-length profile (one with no profile data) and attach it to the color.
If you have access to a profile structure, either as a resource or through calls to the ColorSync Utilities, you can turn that structure into a QuickDraw GX color profile by creating a color profile object with that structure as the profile data.
If your application is a scanning application, it can create a color profile object from information in the scanner's driver and attach that profile to the bitmap shapes it creates.
If your application is a calibration program that develops profile information for a device, it can create a color profile object to hold the profile information it generates during the calibration process and to display the results to the operator of the calibration program.

If your program is a device driver, it contains profile information in the form of color profile resources; it does not need to create color profile objects. How device drivers
store color profile information is described in the printing resources chapter of Inside Macintosh: QuickDraw GX Printing Extensions and Printer Drivers.
To delete your application's reference to a color set or color profile object, call the GXDisposeColorSet or GXDisposeColorProfile function. Calling either function may or may not actually release the memory allocated for the object, depending on the object's owner count. Both of these functions decrease the owner count of the color set or color profile by 1; if that brings the owner count to zero, the object is completely deleted and its memory released. See "Manipulating Owner Counts" on page 4-46.
The GXNewColorSet function is described on page 4-64; the GXNewColorProfile function is described on page 4-79. The GXDisposeColorSet function is described on page 4-65; the GXDisposeColorProfile function is described on page 4-80.

Copying, Comparing, and Cloning Color Sets and Color Profiles
You can use the GXCopyToColorSet function to copy color information from one color set object to another or to create a new copy of an existing color set. You can use the GXCopyToColorProfile function to copy profile information from one color profile object to another or to create a new copy of an existing color profile.
You can test if two references refer to the same color set or color profile object by simply comparing the references for equality. You can also test two different color set or color profile objects for equality with the GXEqualColorSet and GXEqualColorProfile functions, respectively. For two color sets to be equal, their color spaces and colors must be identical; for two color profiles to be equal, their profile information and their attributes must be equal. In either case, the common object properties (owner count and tag list) do not need to be identical for the objects to be considered equal.
Object copies created with the GXCopyToColorSet and GXCopyToColorProfile functions are always equal, in terms of the criteria just listed, to the objects from which they were copied.
In certain circumstances, you may want to copy a reference to a color set or color profile without actually copying the object. For example, you may want two variables to refer to the same color set or color profile object, so that altering one of them affects both. This is called cloning an object, rather than copying it. You can use the GXCloneColorSet and GXCloneColorProfile functions to clone a color set or color profile, respectively.
Functionally, GXCloneColorSet and GXCloneColorProfile do nothing more than increase the owner count of the specified object. For more information about cloning objects, see the chapter "Introduction to Objects" in this book. For information on manipulating owner counts, see the section "Manipulating Owner Counts" on page 4-46.
The following code fragment initializes a bitmap structure to be used for offscreen drawing, assigns a color set object (commonColorSet) to it, and then creates a bitmap shape (shMap) with that bitmap. The code, for its own purposes of tracking owner count (not shown here), clones the color set rather than just assigning it to the bitmap shape. In general, cloning is not necessary when you assign a color set to a bitmap, because when you then call GXNewBitmap to create the bitmap shape (as this code fragment does), QuickDraw GX increases the color set's owner count for you.
gxBitmap          map;
gxPoint           pt = {0, 0};
gxShape           shMap = nil;
.
.  /* set the bitmap's width, height, and pixel size */
.
map.rowBytes = 0L;
map.image = nil;
map.space = gxIndexedSpace;
map.profile = nil;
map.set = GXCloneColorSet(commonColorSet);
shMap = GXNewBitmap(&map, &pt);
QuickDraw GX will decrease the owner count of the color set when the shape shMap is disposed of, but the application code will also need to call GXDisposeColorSet at some point, to balance the GXCloneColorSet call it makes here.
The GXCopyToColorSet function is described on page 4-66; the GXCopyToColorProfile function is described on page 4-81. The GXEqualColorSet function is described on page 4-67; the GXEqualColorProfile function is described on page 4-82. The GXCloneColorSet function is described on page 4-68; the GXCloneColorProfile function is described on page 4-83.

Loading and Unloading Color Sets and Color Profiles
Although you rarely need to, you can influence memory-allocation decisions involving objects that you have created. If your application needs to have a color set object or color profile object in memory, it can force QuickDraw GX to load the object into memory. When your application no longer needs the color set or color profile in a loaded state, it can instruct QuickDraw GX to unload the object.
You call the GXLoadColorSet or GXLoadColorProfile function to make sure
that a color set or color profile object is in memory; if it has been unloaded, QuickDraw GX brings it into memory. You can call the GXUnloadColorSet or GXUnloadColorProfile function to instruct QuickDraw GX that it is free to unload the color set or color profile at any time. These functions are described in the memory management chapter of Inside Macintosh: QuickDraw GX Environment and Utilities.